Work safely on a live site

What you'll see

You want to point Claude Code (or any AI agent) straight at a Docly site and let it work — read the templates, make changes, verify in the browser, iterate. There is no build step, no deploy pipeline and no staging copy: the folder on disk is production. Save a file and it is live for every visitor on the next request. That immediacy is exactly what makes an agent so productive here, and exactly what makes a single careless edit instantly public. This article covers how to work this way safely, and when not to work this way at all.

What's actually happening

Why this way of working is worth the risk. On a conventional stack, an AI agent is separated from the running site by a build, a pull request, a CI run and a deploy. On Docly it edits the site directly: read a .hash template, change it, reload the page, see the result. A loop that takes twenty minutes elsewhere takes twenty seconds here. An agent can genuinely build a new page, wire it into the menu and sitemap, verify it in a real browser and measure it — in one sitting. The value creation is real and it is fast.

Why that same property is the danger. Everything that normally protects you is absent:

• No version control. There is no git revert. If you overwrite a file and did not keep a copy, the previous version is gone.
• No staging. There is no place to be wrong in private. Mistakes are published at the moment of saving.
• No build to fail. A syntax error in a static .js file is not caught by anything — it just silently stops working in visitors' browsers.
• Caching hides breakage from you specifically. Your browser holds the previous version of a static asset, so the page keeps working perfectly for you while it is broken for everyone with a cold cache.

A worked example of all four at once. On dops.no an agent edited boot.js — the small loader that pulls in jQuery, Bootstrap, Swiper, Typed and everything else — by running a node -e "…replace…" one-liner. The shell-to-node-to-JS escaping lost a single backslash, turning the regex /^\/index5/i into /^/index5/i. That is a syntax error, so the whole file failed to parse and nothing loaded: no menu interactions, no carousels, no typed animation, no form submission. It stayed that way for 40 minutes on a live commercial site. The agent had "verified in the browser" and watched jQuery and Typed run happily — from cache. The one check it trusted was the one check that could not detect the fault.

None of the four failures were exotic. They are the default conditions of working on a Docly site, and they are why the practices below are not optional ceremony.

Blast radius: know what you are touching

Before any edit, know how many pages it reaches. Roughly, in increasing order of danger:

1. A new file — safest. It overwrites nothing and nobody links to it yet.
2. A single content page — contained. Worst case, one page is wrong.
3. A display template (#/Tjenesteside.hash, #/Nyhetssak.hash) — every document rendered through it.
4. A master, head, menu or footer (#/master-dark.hash, #/Head.hash, #/menu.hash, #/footer.hash) — every page on the site.
5. A shared static asset (/assets/js/boot.js, bundle.css) — every page, and cached, so a mistake outlives the fix.

Levels 4 and 5 are where an agent can take the whole site down in one edit. Treat them as a different category of work, not just a bigger file.

When not to do this at all

This workflow trades safety for speed. That trade is sensible on a low-traffic marketing site and reckless elsewhere. Do not point an agent at a live site when:

• Traffic is high. A 40-minute breakage on a quiet site is an embarrassment; on a busy one it is lost revenue and a support queue. The cost of a mistake scales with visitors per minute.
• The site takes money or handles transactions. Checkout, booking and payment flows are never worth improvising on.
• The site is behind a login or handles personal data. A layout mistake is recoverable; leaking data is not.
• The content is regulated — consent, privacy and cookie flows have legal ordering requirements. Performance is not a good enough reason to reorder them, and an agent is not the right party to judge that.
• It is peak business hours and nobody is watching. Do risky edits when someone can notice and revert.

For those sites, work on a copy and move the result across — or accept that the review overhead is the price of the risk profile.

What to do

These are the practices that make agent-on-live-site work sustainable. They cost minutes; the failures they prevent cost hours and are public while they last.

1. Back up before touching anything you did not create

There is no git revert. Before editing any existing file, copy it somewhere dated:

mkdir -p _backup-20260717
cp "#/menu.hash" _backup-20260717/menu.hash.bak

New files need no backup — they overwrite nothing. Edits to shared files (master, head, menu, footer, static assets) always do. If you find yourself editing a level-4 or level-5 file without a backup, stop.

2. Never write JavaScript into production files via shell or node escaping

This is the single most dangerous habit, because the network drive fails often and the tempting fallback is node -e "…replace…". Double escaping (shell → node → JS string → regex) is not reviewable by eye, and one lost backslash is a syntax error that stops the whole file. Edit files directly with a file-editing tool. If the drive fails, retry — it comes back. Do not switch to a more dangerous tool because a safe one is flaky.

After any edit to a .js file, syntax-check it before walking away:

node -e "new (require('vm').Script)(require('fs').readFileSync('path/to/file.js','utf8'))" && echo OK

When you must generate structured content (e.g. a .docly file), parse and re-serialise with JSON.parse/JSON.stringify and read the long text fields from separate files. Never hand-escape.

3. Verify with a cold cache, not in your warm browser

Use the Claude Chrome plugin for real verification — it is the only way to catch broken layout, unloaded images, dead SVGs and console errors that source-reading never reveals. Open the page, read the console and network tab, run JS against the live DOM, confirm the thing you changed actually behaves.

But understand its one blind spot: your browser serves cached static assets. If you changed /assets/js/boot.js, your browser is probably still running the old one and will show you a working site regardless. Confirm cold-cache by one of:

• a Lighthouse or PSI run (fresh profile, empty cache);
• fetching the asset with a cache-busting query (fetch('/assets/js/boot.js?cb='+Date.now())) and checking the served content is what you wrote;
• checking the network panel shows the request, not (from disk cache).

Verifying a static-asset change in a warm browser is not weak evidence — it is no evidence.

4. Bump ?v= or your fix reaches nobody

Static /assets/ files have no automatic cache-busting. Change one and returning visitors keep the old version until their cache expires. Bump the ?v= in the referencing file. Files referenced with no version at all are the dangerous ones — add one. See Cache-busting bundles with assetUrl.

5. Experiment on throwaway pages, never with gates in shared files

To test a variant, copy the page (index2.hash, index4.hash…) and change exactly one thing. Give every test page noindex,nofollow so it is never indexed as duplicate content:

<meta id="robots" xdt:Transform="SetAttributes"
      name="robots" content="noindex,nofollow" />

If the variant needs different shared files, copy those too (master-test.hash, Head-minimal.hash) rather than adding conditionals to the real ones. Do not put test gates in shared production files — that is how a measurement experiment becomes a site outage. Delete the test pages when done.

6. One change at a time, verified before the next

When several edits land between verifications and something breaks, you have no idea which one did it — and on a live site you are debugging in public. Change one thing, verify, then continue. This also happens to be the only way to know whether a change actually helped.

7. Report honestly and revert cleanly

If you break something, say so plainly and immediately, with what broke, for how long, and who was affected. A quiet fix denies the owner information they need. And when an experiment shows no effect, revert it — do not leave speculative changes in production "in case they help". Every unreverted experiment is a future debugging session for somebody else.

Checklist before pointing an agent at a live site

1. Is this site low-traffic, non-transactional and not behind a login? If not, do not do this.
2. Is someone available to notice and revert if it goes wrong?
3. Do you know the blast radius of the files in scope (one page, one template, or every page)?
4. Are backups taken for every existing file that will be edited?
5. Are test variants on noindex throwaway pages rather than gated in shared files?
6. Will every .js edit be made with a file editor and syntax-checked — never via shell escaping?
7. Will verification be cold-cache, not just "it looks fine in my browser"?
8. Are changed static assets ?v=-bumped?
9. Are test pages and temporary files deleted afterwards?

See also Optimize page performance (the measurement discipline that goes with this), Cache-busting bundles with assetUrl, Hash files are cached, Creating new docly files, and Use master pages for shared layout.